---
title: Astro를 수동으로 설치하기
description: 'NPM, PNPM, Yarn을 사용하여 Astro를 수동으로 설치하기'
i18nReady: true
---
import Button from '~/components/Button.astro';
import { FileTree } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro'

이 가이드는 새로운 Astro 프로젝트를 수동으로 설치하고 구성하는 단계를 안내합니다.

:::tip[더 빠르게 시작하는 방법을 원하시나요?]
대신 [astro CLI 마법사 생성하기](/ko/install/auto/)를 따르세요.
:::

#### 요구 사항

- **Node.js** - `v18.14.1` 또는 상위 버전.
- **텍스트 편집기** - [VS Code](https://code.visualstudio.com/)와 [공식 Astro 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode)을 함께 사용하는 것이 권장됩니다.
- **터미널** - Astro를 제어할 명령줄 인터페이스(CLI)가 필요합니다.

#### 설치

자동 `create astro` CLI 도구를 사용하는 것을 선호하지 않는다면, 아래 가이드에 따라 프로젝트를 직접 설정할 수 있습니다.

## 1. 디렉터리 생성

프로젝트 이름으로 빈 디렉터리를 생성한 후, 해당 디렉터리로 이동합니다.

```bash
mkdir my-astro-project
cd my-astro-project
```

새 디렉터리에 `package.json` 파일을 생성합니다. 이 파일을 통해 Astro를 포함한 프로젝트 종속성을 관리하게 될 것입니다. 이 파일의 형식에 익숙하지 않은 경우, 다음 명령을 통해 파일을 생성하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm init --yes
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm init 
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn init --yes
  ```
  </Fragment>
</PackageManagerTabs>

## 2. Astro 설치

먼저, 프로젝트에 Astro 패키지를 설치하세요.

:::note[중요]

Astro는 전역이 아닌 로컬에 설치되어야 합니다. 실수로 `npm install -g astro`, `pnpm add -g astro`, `yarn add global astro` 명령을 실행하지 *않도록* 주의하세요.
:::

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add astro
  ```
  </Fragment>
</PackageManagerTabs>

그리고 `package.json` 파일의 "scripts" 섹션의 값을 다음과 같이 변경합니다.

```json title="package.json" del={2} ins={3-6}
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```

나중에 이 스크립트는 Astro를 시작하고 다양한 명령을 실행하는 데 사용됩니다.

## 3. 첫 페이지 생성

텍스트 편집기로 디렉터리에 새 `src/pages/index.astro` 파일을 생성합니다. 이 파일은 프로젝트의 첫 Astro 페이지가 될 것입니다.

이 가이드에서는 다음 코드(대시 `---` 포함)를 복사하여 사용하세요.

```astro title="src/pages/index.astro"
---
// Astro에 오신 것을 환영합니다! 코드 펜스(삼중 대시로 구별됨) 사이에 있는 모든 것은
// "컴포넌트의 frontmatter"이며, 브라우저에서는 실행되지 않습니다.
console.log('터미널에서 실행되며, 브라우저에서는 실행되지 않습니다!');
---
<!-- 아래 코드는 "컴포넌트 템플릿"입니다.
     훌륭한 템플릿을 구축하기 위한 몇 가지 마법이 추가된 HTML입니다. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>
```

## 4. 첫 번째 정적 자산 만들기

또한, 정적 자산을 저장하기 위해 `public/` 디렉터리를 사용할 수도 있습니다. Astro는 항상 최종 빌드에 이러한 자산을 포함하므로 컴포넌트 템플릿 내부에서 안전하게 참조할 수 있습니다.

텍스트 편집기에서 새 `public/robots.txt` 파일을 생성합니다. `robots.txt`는 Google과 같은 검색 봇에게 사이트 처리 방법을 알려주기 위해 대부분의 사이트에 포함되는 간단한 파일입니다.

이 가이드에서는 다음 코드를 복사하여 사용하세요.

```diff title="public/robots.txt"
# 예: 모든 봇이 사이트를 스캔하고 색인을 생성하는 것을 허용합니다.
# 전체 구문: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```

## 5. `astro.config.mjs` 생성

Astro는 `astro.config.mjs`를 통해 구성됩니다. Astro를 구성할 필요가 없다면 이 파일은 선택 사항이지만, 지금 생성하는 것이 좋습니다.

프로젝트 루트 디렉터리에 `astro.config.mjs`를 생성하고 아래 코드를 복사하여 사용하세요.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```

프로젝트에 React, Svelte 등과 같은 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/)를 포함하거나 Tailwind 또는 Partytown과 같은 다른 도구를 사용하려는 경우 이 파일에서 [직접 통합을 가져오고 구성](/ko/guides/integrations-guide/)할 수 있습니다.

<ReadMore>자세한 내용은 Astro의 [API 구성 참조](/ko/reference/configuration-reference/)를 확인하세요.</ReadMore>

## 6. TypeScript 지원 추가

TypeScript는 `tsconfig.json`를 통해 구성됩니다. TypeScript 코드를 작성하지 않더라도 Astro 및 VS Code와 같은 도구가 프로젝트를 이해하는데 도움을 준다는 점에서 이 파일은 중요합니다. 일부 기능(예: npm 패키지 가져오기)은 `tsconfig.json` 파일이 없으면 편집기에서 완전히 지원되지 않습니다.

TypeScript 코드를 작성하려는 경우, Astro의 `strict` 또는 `strictest` 템플릿을 사용하는 것을 권장합니다. [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/)에서 세 가지 템플릿 구성을 확인하고 비교할 수 있습니다.

프로젝트 루트 디렉터리에 `tsconfig.json` 파일을 생성하고 아래 코드를 복사하여 사용합니다. (TypeScript 템플릿으로 `base`, `strict`, `strictest`를 사용할 수 있습니다)

```json title="tsconfig.json" "base"
{
  "extends": "astro/tsconfigs/base"
}
```

마지막으로, `src/env.d.ts`를 생성하여 TypeScript가 Astro 프로젝트에서 사용할 수 있는 타입을 알 수 있도록 합니다.

```ts title="src/env.d.ts"
/// <reference types="astro/client" />
```

<ReadMore>자세한 내용은 [TypeScript 설정 가이드](/ko/guides/typescript/#설정)를 참조하세요.</ReadMore>

## 7. 다음 단계

위 단계를 모두 수행했다면 프로젝트의 디렉터리는 다음과 같은 형태가 됩니다.

<FileTree>
- node_modules/
- public/
  - robots.txt
- src/
  - pages/
    - index.astro
  - env.d.ts
- astro.config.mjs
- package-lock.json 또는 `yarn.lock`, `pnpm-lock.yaml` 등.
- package.json
- tsconfig.json
</FileTree>

축하합니다, 이제 Astro를 사용할 준비가 되었습니다!

이 가이드를 완전히 따랐다면 [2단계: Astro 시작하기](/ko/install/auto/#2-astro-시작하기-)로 이동하여 Astro를 실행하는 방법에 대해 알아보세요.
